/**
 * Copyright  (c) 2009-2013 XLab,  Org. 
 * All  rights  reserved. 
 */
package org.xlab.baseframework.service.api;

import java.util.List;

import org.springframework.transaction.annotation.Transactional;
import org.xlab.baseframework.annotation.Loggable;
import org.xlab.baseframework.domain.ISystemUserDomain;
import org.xlab.baseframework.domain.SystemCode;
import org.xlab.baseframework.domain.enumerate.EnumDeletedIndentifying;
import org.xlab.baseframework.domain.view.SystemCodeVO;
import org.xlab.baseframework.exception.SystemCodeDuplicateException;
import org.xlab.baseframework.exception.SystemCodeNotFoundException;

/**
 * <p>
 * 系统编码服务接口
 * </p>
 * 
 * @author MaKuBEX Email:makubexnet@gmail.com
 * @version 1.0.0 Sep 9, 2010
 * @since 1.0.0
 * 
 */
public interface ISystemCodeService extends
		IBaseService<SystemCodeVO, SystemCode> {

	/**
	 * <p>
	 * 创建系统代码
	 * </p>
	 * 
	 * @param code
	 *            代码
	 * @param description
	 *            代码描述
	 * @param sequence
	 *            代码序列
	 * @param category
	 *            代码分类
	 * @param createdBy
	 *            创建人
	 * @throws SystemCodeDuplicateException
	 *             如果需要创建的系统代码已经存在
	 */
	@Loggable
	@Transactional
	public void createSystemCode(String code, String description,
			Long sequence, SystemCode category, ISystemUserDomain createdBy)
			throws SystemCodeDuplicateException;

	/**
	 * <p>
	 * 移除一个系统代码
	 * </p>
	 * 
	 * @param code
	 *            代码
	 * @param deletedBy
	 *            移除人
	 */
	@Loggable
	@Transactional
	public void deleteSystemCode(SystemCode systemCode,
			ISystemUserDomain deletedBy);

	/**
	 * <p>
	 * 获取所有系统代码
	 * </p>
	 * 
	 * @return 所有系统代码
	 * @throws SystemCodeNotFoundException
	 *             没有任何系统代码记录被找到
	 */
	public List<SystemCode> findAll() throws SystemCodeNotFoundException;

	/**
	 * <p>
	 * 查找出一个类别下的所有的直属或者全部系统代码集合
	 * </p>
	 * 
	 * @param category
	 *            类别
	 * @param useCache
	 *            是否从缓存中获取
	 * @param directlyOnly
	 *            是否只查找直属数据
	 * @return 系统代码集合
	 * @throws SystemCodeNotFoundException
	 *             如果该类型没有任何记录被找到
	 */
	public List<SystemCode> findAllByCategory(SystemCode category,
			boolean useCache, boolean directlyOnly)
			throws SystemCodeNotFoundException;

	/**
	 * <p>
	 * 根据删除标识符来获取所有代码
	 * </p>
	 * 
	 * @param deletedInd
	 *            删除标识符
	 * @return 所有状态符合条件的系统代码
	 * @throws SystemCodeNotFoundException
	 *             没有任何系统代码记录被找到
	 */
	public List<SystemCode> findAllByDeletedInd(
			EnumDeletedIndentifying deletedInd)
			throws SystemCodeNotFoundException;

	/**
	 * <p>
	 * 根据提供的代码查找系统代码实体
	 * </p>
	 * 
	 * @param code
	 *            代码
	 * @param useCache
	 *            是否从缓存中获取
	 * @return 系统代码实体
	 * @throws SystemCodeNotFoundException
	 *             如果该代码没有被找到
	 * @throws SystemCodeDuplicateException
	 *             如果该代码被发现存在一条以上的记录
	 */
	public SystemCode findByCode(String code, boolean useCache)
			throws SystemCodeNotFoundException, SystemCodeDuplicateException;

	/**
	 * <p>
	 * 根据提供的代码主键在数据库中查找对应的代码实体
	 * </p>
	 * 
	 * @param id
	 *            代码主键
	 * @return 系统代码实体
	 * @throws SystemCodeNotFoundException
	 *             如果该代码没有被找到
	 */
	public SystemCode findById(Long id) throws SystemCodeNotFoundException;

	/**
	 * <p>
	 * 还原一个被删除的系统代码
	 * </p>
	 * 
	 * @param systemCode
	 *            系统代码
	 * @param restoreBy
	 *            还原者
	 * @throws SystemCodeNotFoundException
	 *             如果系统中不存在该代码
	 */
	@Loggable
	@Transactional
	public void restoreSystemCode(SystemCode systemCode,
			ISystemUserDomain restoreBy);

	/**
	 * <p>
	 * 更新一个系统代码
	 * </p>
	 * 
	 * @param code
	 *            代码
	 * @param updatedBy
	 *            更新人
	 * @throws SystemCodeNotFoundException
	 *             如果系统参数没有被找到
	 */
	@Loggable
	@Transactional
	public void updateSystemCode(SystemCode systemCode,
			ISystemUserDomain updatedBy) throws SystemCodeNotFoundException;
}
